package org.as3lib.utils
{
	import flash.geom.Point;

	/**
	 * Provides a set of functions for generating random numbers.
	 */
	public class RandomUtil
	{
		
		/**
		 * Randomly generates a number in a range between low and high inclusively.
		 * Automatically swaps high and low if low is higher.
		 */
		public static function getRandomNumberBetween(low:Number, high:Number):Number {
			if (low > high) {
				var temp:Number = high;
				high = low;
				low = temp;
			}
			return Math.random() * (high - low) + low;
		}
		
		/**
		 * Randomly generates an integer in a range between low and high inclusively.
		 */
		public static function getRandomIntBetween(low:int, high:int):int {
			return Math.round(getRandomNumberBetween(low, high));
		}
		
		/**
		 * Randomly returns true "percent"% of the time (where percent is a decimal between 0.0 and 1.0).
		 */
		public static function getRandomChance(percent:Number):Boolean {
			return Math.random() < percent;
		}
		
		/**
		 * Randomly returns either true or false.
		 */
		public static function getRandomBoolean():Boolean {
			return getRandomChance(0.5);
		}
		
		
		/**
		 * Generates an int that is either -1, 0, or 1.
		 */
		public static function getRandomTrinary():int {
			return getRandomIntBetween(-1, 1);
		}
		
		/**
		 * Returns a random color between 0x000000 and 0xFFFFFF
		 */
		public static function getRandomColor():uint {
			return uint(Math.random() * 0xFFFFFF);
		}
		
		/**
		 * Returns a random element from an array.
		 */
		public static function getRandomElement(array:Array):* {
			return array[getRandomIntBetween(0, array.length-1)];
		}
		
		/**
		 * Returns a randomly generated point (containing int values)
		 */
		public static function getRandomPoint(xLow:int, xHigh:int, yLow:int, yHigh:int):Point {
			return new Point(
				getRandomIntBetween(xLow, xHigh),
				getRandomIntBetween(yLow, yHigh)
			);
		}
	}
}